TIMEGEN

The TIMEGEN function returns an array, with specified dimensions, of double-precision floating-point values that represent times in terms of Julian Dates.

The Julian Date is the number of days elapsed since Jan. 1, 4713 B.C.E., plus the time expressed as a day fraction. Following the astronomical convention, the day is defined to start at 12 PM (noon). Julian date 0.0d is therefore Jan. 1, 4713 B.C.E. at 12:00:00.

The first value of the returned array corresponds to a Julian Date start time, and each subsequent value corresponds to the next Julian Date in the sequence. The sequence is determined by specifying the time unit (such as months or seconds) and the step size, or spacing, between the units. You can also construct more complicated arrays by including smaller time units within each major time interval.

A small offset is added to each Julian Date to eliminate roundoff errors when calculating the day fraction from the hour, minute, second. This offset is given by the larger of EPS and EPS*Julian, where Julian is the integer portion of the Julian Date and EPS is the double-precision floating-point precision parameter from MACHAR. For typical Julian Dates the offset is approximately 6x10^-10 (which corresponds to 5x10^-5 seconds). This offset ensures that when the Julian Date is converted back to the hour, minute, and second, the hour, minute, and second will have the same integer values.

Tip: Because of the large magnitude of the Julian Date (1 Jan 2000 is Julian day 2451545), the precision of most Julian Dates is limited to 1 millisecond (0.001 seconds). If you are not interested in the date itself, you can improve the precision by subtracting a large offset or setting the START keyword to zero.

Note: Julian values must be in the range -1095 to 1827933925, which corresponds to calendar dates 1 Jan 4716 B.C.E. and 31 Dec 5000000, respectively.

Examples

Generate an array of 366 time values that are one day apart starting with January 1, 2000:

MyDates = TIMEGEN(366, START=JULDAY(1,1,2000))

Generate an array of 20 time values that are 12 hours apart starting with the current time:

MyTimes = TIMEGEN(20, UNITS='Hours', STEP_SIZE=12, $

START=SYSTIME(/JULIAN))

Generate an array of time values that are 1 hour apart from 1 January 2000 until the current time:

MyTimes = TIMEGEN(START=JULDAY(1,1,2000), $

FINAL=SYSTIME(/JULIAN), UNITS='Hours')

Generate an array of time values composed of seconds, minutes, and hours that start from the current hour:

MyTimes = TIMEGEN(60, 60, 24, $

START=FLOOR(SYSTIME(/JULIAN)*24)/24d, UNITS='S')

Generate an array of 24 time values with monthly intervals, but with subintervals at 5 PM on the first and fifteenth of each month:

MyTimes = TIMEGEN(24, START=FLOOR(SYSTIME(/JULIAN)), $

DAYS=[1,15], HOURS=17)

Generate an array of high-precision time values using Modified Julian Dates:

MyDates = TIMEGEN(86400, START=JULDAY(1,1,2000,0,0,0, /MODIFIED), /MODIFIED, UNITS="seconds")

Syntax

Result = TIMEGEN( [D₁,...,D₈] [, FINAL=value] [, DAYS=vector] [, HOURS=vector] [, MINUTES=vector] [, /MODIFIED] [, MONTHS=vector] [, SECONDS=vector] [, START=value] [, STEP_SIZE=value] [, UNITS=string] [, YEAR=value] )

Return Value

Returns the specified time values.

Arguments

D_i

The dimensions of the result. The dimension parameters may be any scalar expression. Up to eight dimensions may be specified. If the dimension arguments are not integer values, IDL will truncate them to integer values before creating the new array. The dimension arguments are required unless keyword FINAL is set, in which case they are ignored.

Keywords

DAYS

Set this keyword to a scalar or a vector giving the day values that should be included within each month. This keyword is ignored if the UNITS keyword is set to “Days”, “Hours”, “Minutes”, or “Seconds”.

Note: Day values that are beyond the end of the month will be set equal to the last day for that month. For example, setting DAY=[31] will automatically return the last day in each month.

FINAL

Set this keyword to a double-precision value representing the Julian Date to use as the last value in the returned array. In this case, the dimension arguments are ignored and Result is a one-dimensional array, with the number of elements depending upon the step size. The FINAL time may be less than the START time, in which case STEP_SIZE should be negative.

Note: If the step size is not an integer then the last element may not be equal to the FINAL time. In this case, TIMEGEN will return enough elements such that the last element is less than or equal to FINAL.

HOURS

Set this keyword to a scalar or a vector giving the hour values that should be included within each day. This keyword is ignored if UNITS is set to “Hours”, “Minutes”, or “Seconds”.

MINUTES

Set this keyword to a scalar or a vector giving the minute values that should be included within each hour. This keyword is ignored if UNITS is set to “Minutes” or “Seconds”.

MODIFIED

Set this keyword to return Modified Julian Dates, which are regular Julian Dates minus 2400000.5. Modified Julian Dates have a higher precision of approximately 1.2x10^–11(equal to 1x10^–6seconds).

Note: If you are using the START or FINAL keywords, be sure to also specify those dates as Modified Julian Dates.

MONTHS

Set this keyword to a scalar or a vector giving the month values that should be included within each year. This keyword is ignored if UNITS is set to “Months”, “Days”, “Hours”, “Minutes”, or “Seconds”.

SECONDS

Set this keyword to a scalar or a vector giving the second values that should be included within each minute. This keyword is ignored if UNITS is set to “Seconds”.

START

Set this keyword to a double-precision value representing the Julian Date to use as the first value in the returned array. The default is 0.0d [corresponding to January 1, 4713 B.C.E. at 12 pm (noon)].

Note: If subintervals are provided by MONTHS, DAYS, HOURS, MINUTES, or SECONDS, then the first element may not be equal to the START time. In this case the first element in the returned array will be greater than or equal to START.

Tip: For other array generation routines in IDL, such as FINDGEN, you do not need to specify a starting value because you can always add a scalar representing the start value. For TIMEGEN it is correct to add a scalar to the array if the units are days, hours, minutes, seconds, or sub-seconds. For example:
MyTimes = TIMEGEN(365, UNITS="Days") + SYSTIME(/JULIAN)

However, if the units are months or years, the start value is necessary because the number of days in a month or year can vary depending upon the year in which they fall (for instance, consider leap years). For example:
MyTimes = TIMEGEN(12, UNITS="Months", START=JULDAY(1,1,2000))

STEP_SIZE

Set this keyword to a scalar value representing the step size between the major intervals of the returned array. The step size may be negative. The default step size is 1. When the UNITS keyword is set to “Years” or “Months”, the STEP_SIZE value is rounded to the nearest integer.

UNITS

Set this keyword to a scalar string indicating the time units to be used for the major intervals for the generated array. Valid values include:

“Years” or “Y”
“Months” or “M”
“Days” or “D”
“Hours” or “H”
“Minutes” or “I”
“Seconds” or “S”

The case (upper or lower) is ignored. If this keyword is not specified, then the default for UNITS is the time unit that is larger than the largest keyword present:

Largest Keyword Present	Default UNITS
SECONDS=vector	“Minutes”
MINUTES=vector	“Hours”
HOURS=vector	“Days”
DAYS=vector	“Months”
MONTHS=vector	“Years”
YEAR=value	“Years”

If none of the above keywords are present, the default is UNITS=“Days”.

YEAR

Set this keyword to a scalar giving the starting year. If YEAR is specified then the starting year from START is ignored.

Version History

5.4	Introduced
8.8.3	Added MODIFIED keyword